
#ifndef _B5M_QUEUE_H_
#define _B5M_QUEUE_H_

#include "common.h"

B5M_BEGIN_VERSIONED_NAMESPACE_DECL
/**
* @class B5M_Queue
*
* A Queue defines an interface for a value-oriented collection objects (similar to
* STL collections). 
*/
template <typename T>
class B5M_Queue 
{
	public:

	//! Destroy a Queue
	virtual ~B5M_Queue() { }

	/**
	* Add an object to this Queue.
	*
	* @param item value to be added to the Queue
	* 
	* @exception Cancellation_Exception thrown if this Queue has been canceled.
	*
	* @pre  The Queue should not have been canceled prior to the invocation of this function.
	* @post If no exception is thrown, a copy of <i>item</i> will have been added to the Queue.
	*/
	virtual void add(const T& item) = 0;

	/**
	* Add an object to this Queue.
	*
	* @param item value to be added to the Queue
	* @param timeout maximum amount of time (milliseconds) this method may block
	*        the calling thread.
	*
	* @return 
	*   - <em>true</em> if a copy of <i>item</i> can be added before <i>timeout</i> 
	*     milliseconds elapse.
	*   - <em>false</em> otherwise.
	*
	* @exception Cancellation_Exception thrown if this Queue has been canceled.
	*
	* @pre  The Queue should not have been canceled prior to the invocation of this function.
	* @post If this function returns true a copy of <i>item</i> will have been added to the Queue.
	*/
	virtual bool add(const T& item, unsigned long timeout) = 0;

	/**
	* Retrieve and remove a value from this Queue.
	*
	* @return <em>true</em> if next available value
	* 
	*
	* @pre  The Queue should not have been canceled prior to the invocation of this function.
	* @post The value returned will have been removed from the Queue.
	*/
	virtual bool next(T&) = 0;

	/**
	* Retrieve and remove a value from this Queue.
	*
	* @param timeout maximum amount of time (milliseconds) this method may block
	*        the calling thread.
	*
	* @return <em>true</em> if next available value
	* 
	*
	* @pre  The Queue should not have been canceled prior to the invocation of this function.
	* @post The value returned will have been removed from the Queue.
	*/
	virtual bool next(T&,unsigned long timeout) = 0;

	/**
	* Count the values present in this Queue. 
	*
	* @return <em>size_t</em> number of elements available in the Queue. 
	*/
	virtual size_t size() = 0;

	/**
	* Count the values present in this Queue. 
	*
	* @param timeout maximum amount of time (milliseconds) this method may block
	*        the calling thread.
	*
	* @return <em>size_t</em> number of elements available in the Queue. 
	*
	*/
	virtual size_t size(unsigned long timeout) = 0;

	/**
	* Test whether any values are available in this Queue.
	*
	* @return 
	*  - <em>true</em> if there are no values available.
	*  - <em>false</em> if there <i>are</i> values available.
	*/
	virtual bool empty() {
		return size() == 0;
	}

	/**
	* Test whether any values are available in this Queue.
	*
	* @param timeout maximum amount of time (milliseconds) this method may block
	*        the calling thread.
	*
	* @return 
	*  - <em>true</em> if there are no values available.
	*  - <em>false</em> if there <i>are</i> values available.
	*
	*/
	virtual bool empty(unsigned long timeout) {
			return size(timeout) == 0;
	}

}; /* Queue */

B5M_END_VERSIONED_NAMESPACE_DECL

#endif // __ZTQUEUE_H__
